package com.fwzhang.third.collectionframework.collection.queue;

import java.util.Collection;
import java.util.Queue;
import java.util.concurrent.TimeUnit;

/**
 * 阻塞队列接口
 * @param <E>
 */
public interface BlockingQueueInterface<E> extends Queue<E> {

    /**
     * BlockingQueue的实现类中方法声明了InterruptException, 在方法的执行过程中都存在线程等待处理
     */

    /**
     * 在队列中增加元素，
     * 实现方法中不会等待, 队列中无空余空间，会直接返回false
     * @param e
     * @return 增加的结果
     */
    boolean offer(E e);

    /**
     * 队列中增加数据，队列中无可用空间，会进行等待
     * {@link #offer(Object)} 和本方法都会加锁
     *
     * @param e
     * @throws InterruptedException 等待过程中被打断
     */
    void put(E e) throws InterruptedException;

    /**
     * 队列中增加数据
     * @param e 增加的数据
     * @param timeout 指定最长的等待时间数值
     * @param timeUnit 等待时间单位
     * @return
     * @throws InterruptedException 线程等待过程中, 被打断
     */
    boolean offer(E e, long timeout, TimeUnit timeUnit) throws InterruptedException;

    /**
     * 返回并删除队列头部元素
     * @return
     * @throws InterruptedException
     */
    E take() throws InterruptedException;

    /**
     * 返回并删除队列头数据
     * 指定最长的队列等待时间
     * @param timeOut 线程等待时间数值
     * @param timeUnit 线程等待时间单位
     * @return
     * @throws InterruptedException 线程等待时被打断抛出该异常
     */
    E poll(long timeOut, TimeUnit timeUnit) throws InterruptedException;

    /**
     * 将collection集合中可用的元素放入到队列中, 可以指定最大数量
     * 存在同名方法{@link #drainTo(Collection, int)}，指定最大数量，一般最大数量默认为{@code Integer.MAX}
     * @param collection
     * @return
     */
    int drainTo(Collection<? super E> collection);

    int drainTo(Collection<? super E> collection, int maxElements);

}
